# HP OpenView Service Desk

## version 4.5
Migration of attachment folder structure

October 2005

© Copyright 2005 Hewlett-Packard Development Company, L.P.

## Content:

Last-minute information
Introduction
Folder structure reconstruction
Getting Started
Frequently asked questions

## LAST-MINUTE INFORMATION

Users upgrading from SP15 (or earlier) to SP16 (or higher) must migrate existing attachment folder structure.

## INTRODUCTION

In Service Desk 4.5, attachments are stored as files on a FTP server. According to the current folder structure, attachments of same type item are stored in single folder. Since some file systems impose a physical limit on the number of entries within a single folder, Service Desk cannot store large number of attachments of same type item. In service pack 16 the folder structure is changed for storing more attachments. The existing attachments in service desk have to be migrated into this new structure.

This guide gives a step by step plan for migrating existing attachments step by step.

## FOLDER STRUCTURE RECONSTRUCtION

Service Desk 4.5 (pre service pack 16) used the following attachment folder structure:

        \Attachmentroot\Entitytype-name\Entity-oid\Attachment-oid

Entity is the technical term for items in Service Desk. OID means object id which is internal representation of items in service desk.

For example, there are 3 service calls with 2 attachments each

Service call OID | Attachment OID
281479802001001 | 281479802002001, 281479802002002
281479802001002 | 281479802002003, 281479802002004
281479802001003 | 281479802002005, 281479802002006

The old attachment folder structure is listed as following:

        Root folder in FTP server = /opt/OV/sd/attachments

Attachments are stored in:

        /opt/OV/sd/attachments/servicecall/281479802001001/281479802002001
        /opt/OV/sd/attachments/servicecall/281479802001001/281479802002002
        /opt/OV/sd/attachments/servicecall/281479802001002/281479802002003
        /opt/OV/sd/attachments/servicecall/281479802001002/281479802002004
        /opt/OV/sd/attachments/servicecall/281479802001003/281479802002005
        /opt/OV/sd/attachments/servicecall/281479802001003/281479802002006

Some file systems impose a physical limit on the number of entries that may be stored within a single folder. The following table lists some of the most common types in use by our installed base:

OS | Version | Limit
HP-UX | Standard | 32767
HP-UX | PHKL_28185 | 65534
Windows | FAT32 | 65534
Windows | NTFS | 4,294,967,295 Files per volume

When the number of items of the same type reaches this limit, it is no longer possible to attach files.

The new folder structure is constructed as following:

        \Attachmentroot\Entitytype-name\Entity-uuid-fragements1...11\Attachment-uuid

UUID (Universally Unique Identifiers) is generated from object OID. It is 128 bits (16 bytes) long. Entity-uuid-fragements1...11 represents breaking entity uuid into 11 fragments. The first ten fragments are 3 bytes long each and the last fragment is 2 bytes long.

Entity-uuid is generated from entity OID and Attachment-uuid is generated from attachment OID. Attachment-uuid uses the following format (where H is a hexadecimal number):

        HHHHHHHH-HHHH-HHHH-HHHH-HHHHHHHHHHHH

In new attachments folder structure, a Service call attachment path will be like:

        Attachmentroot\Servicecall\000\000\000\000\000\000\010\000\c31\100\fa\00000000-0000-0000-0001-0000c6280140

Compared to the old attachments folder structure, the number of entries in any folder decreases to 163=4096 which is well below the limit. So it won't cause mentioned limitation.

The change requires the existing attachments in service desk to be migrated to new structure.

## GETTING STARTED

### Install Perl 5.8

Before running the migration script, Perl 5.8 must be installed on FTP server.

OS | Download website
Windows | http://www.activestate.com/Products/ActivePerl/
HP-UX | http://hpux.cs.utah.edu/hppd/hpux/Languages/perl-5.8.7/
Solaris | http://www.activestate.com/Products/ActivePerl/

After installing perl on FTP server, please verify perl version by executing command line

        perl -version

The version must be higher or equal 5.8.

### How to execute migration script

Preliminary: Execution privilege to Perl application and full access to attachment folder is required.

It is recommended to backup old attachments before executing the migration script.

Execute <service pack extraction folder>\doc\itsm007474\mig_attachments.pl on FTP server in shell or command line.

        perl mig_attachments.pl [-c] <sourcedir> <targetdir>

Also please make sure to log the output of the script by redirecting the standard output and standard error to a log file. On Unix shells, this is usually done as "> outputfile.log 2>&1".

        perl mig_attachments.pl olderfolder newfolder > migoutputfile.log 2 > & 1

On Windows shells (NON-FAT file system), type following command:

        perl mig_attachments.pl olderfolder newfolder > migoutputfile.log 2 > & 1

On Windows shells (FAT32 or FAT16 file system), type following command:

        perl mig_attachments.pl -c olderfolder newfolder > migoutputfile.log 2 > & 1

After execution please check the migoutputfile.log to find migration result.

### Hard link vs. Actual file copy

By default, the script creates hard links from the current attachment folder structure to the new attachment folder structure. A hard link is an additional reference to an existing file or directory on a disk. By using hard links, the amount of space required for the migration is limited to the overhead of having a new directory structure and the additional references. The performance is high compared to actual copying the file data.

Many operating systems have limitations on the use of hard links. On many Unix systems, it is not allowed to create hard links across different partitions. On Windows, hard links are only allowed on NTFS file systems.

If for some reason you cannot use hard links on your FTP server, you can specify the -c option as first argument to mig_attachments.pl, which will instruct the migration program to copy the files to their new structure instead of hard linking them. Using -c option, disk space reserved should be at least the same as that of existing attachments. Also the time consumed will be greater.

Item | Use Hard link | Use Actual File Copy
Performance | High (less than half hour) | Low (few hours)
Disk Space | Little | Same disk space used by existing files
Script execution | No additional parameter | -c option

### Migration strategy I: offline migration

Offline strategy is applicable for file system which supports hard link (faster migration).

Detailed steps are:

1. Install perl 5.8 or higher.
2. Stop application server.
3. Back up existing attachments.
4. Create new attachment root folder and check disk space.
5. Execute the migration script.
6. Upgrade service desk.
7. Start application server and client, change folder of attachment setting.
   Tools > System > System Panel > Attachments Settings> Change Target folder to 'newfolder'

### Migration strategy II: online migration

Online strategy is applicable for file system which DOES NOT support hard link (slower migration).

Detailed steps are:

1. Install perl 5.8 or higher.
2. Back up existing attachments.
3. Create new attachment root folder and check disk space.
4. Execute the migration script using -c option while the service desk of old version is still running (This won't impact the attachment function as the script only copies the attachments).
5. After first round of migration is finished, stop the application server.
6. Upgrade service desk.
7. Execute the migration script using -c option again to migrate the files changed after first round migration started. The second round will take less time because no effort will be made to link or copy files that already have been migrated.
8. Start application server and client, change folder of attachment setting.

## FREQUENTLY ASKED QUESTIONS

Q: Why doesn't my perl version change after installing new one?

A: Sometimes perl command is a link to real perl execution file. The perl command keeps the original link even when you have installed a newer version. You should change the link to new version perl execution file. Another possible reason is that in environment variable path the original perl execution file is prior to new one.

Q: Does migration destroy original attachment folder structure?

A: The migration just copies original attachment files. So it won't cause any corruption on the original folder structure and files.

Q: How about the migration performance?

A: There is no performance issue in case that file system supports hard link. For file system not supporting hard link it will take more time to migrate. Usually it will be few hours based on the number of attachments and hard disk speed. Please refer to Hard link vs. Actual file copy.

Q: How much disk space do I need to reserve?

A: Only little (additional) disk space is required in case that file system supports hard link. For file system not supporting hard link at least the same amount disk space should be reserved as consumed by the original attachments. Please refer to Hard link vs. Actual file copy.

Q: Could you recommend steps regarding migration?

A: For faster migration we recommend to use Migration strategy I: offline migration. For slower migration we recommend to use Migration strategy II: online migration.

Q: Does the execution of migration script depend on application server?

A: No.

Q: Can user access attachments when migration is being executing?

A: Users can access those attachments when migration is going because the migration just copies the original attachments.

Q: Can I delete old attachment folder after migration?

A: Yes. You can delete old attachments safely no matter you are using hard link or actual file copy.

Q: Could you explain the new attachment folder structure?

A: Please refer to Folder Structure Reconstruction.

Q: How about the compatibility with SD 5.0?

A: The new attachments folder is compatible with SD 5.0.